/*
 * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 *
 */

package java.util;

import java.util.function.Consumer;

/**
 * 一个集合的迭代器。
 * Iterator需要的地方Enumeration在Java集合框架。 迭代器有两种不同的枚举方式：
 * 1、迭代器允许调用者在迭代期间从底层集合中删除元素，并具有明确定义的语义。
 * 2、方法名称得到改进。
 *
 * @see Collection
 * @see ListIterator
 * @see Iterable
 * @since 1.2
 */
public interface Iterator<E> {
    /**
     * 如果迭代具有更多的元素，则返回true 。
     * 换句话说，如果next()返回一个元素而不是抛出一个异常，则返回true
     * @return true如果迭代有更多的元素
     */
    boolean hasNext();

    /**
     * 返回迭代中的下一个元素。
     * @return 迭代中的下一个元素
     * @throws NoSuchElementException 如果迭代没有更多的元素
     */
    E next();

    /**
     * 从底层集合中删除此迭代器返回的最后一个元素（可选操作）。
     * 此方法只能调用一次next()
     * 如果底层集合在迭代过程中以任何方式进行修改而不是通过调用此方法，则迭代器的行为是未指定的。
     * @throws UnsupportedOperationException 如果 remove操作不会被这个迭代器支持
     * @throws IllegalStateException         如果 next方法尚未被调用，或者 remove方法在上次调用 next方法之后已经被调用
     **/
    default void remove() {
        throw new UnsupportedOperationException("remove");
    }

    /**
     * 对每个剩余元素执行给定的操作，直到所有元素都被处理或动作引发异常。
     * 如果指定了该顺序，则按迭代的顺序执行操作。 动作抛出的异常被转发给呼叫者。
     * @param action 要为每个元素执行的操作
     * @throws NullPointerException 如果指定的动作为空
     * @since 1.8
     */
    default void forEachRemaining(Consumer<? super E> action) {
        Objects.requireNonNull(action);
        while (hasNext())
            action.accept(next());
    }
}
